# Pug Plugin

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-pug" />

The Pug plugin provides support for the Pug template engine. Pug is a robust, elegant, feature rich template engine for Node.js.

## Quick Start

### Install Plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-pug -D" />

### Register Plugin

You can register the plugin in the `rsbuild.config.ts` file:

```ts title="rsbuild.config.ts"
import { pluginPug } from '@rsbuild/plugin-pug';

export default {
  plugins: [pluginPug()],
};
```

### Using Pug Templates

After the plugin registration is completed, Rsbuild will automatically parse template files with the `.pug` extension and compile them using the Pug template engine.

For example, first create a `src/index.pug` file, and point to that file using `html.template`:

```ts title="rsbuild.config.ts"
export default {
  html: {
    template: './src/index.pug',
  },
};
```

Then, you can use Pug syntax in the `index.pug` template:

```html
<!-- Input -->
p Hello #{text}!

<!-- Output -->
<p>Hello World!</p>
```

Please refer to the [Pug documentation](https://pugjs.org/) for a complete understanding of Pug's usage.

### Using in Vue

When using Vue, you can use Pug syntax in the template of `.vue` files:

```vue title="App.vue"
<template lang="pug">
button.my-button(@click='count++') Count is: {{ count }}
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const count = ref(0);

    return {
      count,
    };
  },
};
</script>
```

## Options

### pugOptions

Used to set the compilation options for Pug. For detailed options, please refer to the [Pug API Reference](https://pugjs.org/api/reference.html#options).

- **Type:** `Object | Function | undefined`
- **Default:**

```ts
const defaultOptions = {
  doctype: 'html',
  compileDebug: false,
};
```

- **Example 1:** Pass in a configuration object that will be merged with the default options using `Object.assign`.

```ts
pluginPug({
  pugOptions: {
    doctype: 'xml',
  },
});
```

- **Example 2:** Pass in a configuration function. The default configuration will be passed as the first argument, and you can directly modify the configuration object or return a value as the final result.

```ts
pluginPug({
  pugOptions(config) {
    config.doctype = 'xml';
  },
});
```
